Provinence

You can always find the latest version of this document in the E3 Documentation in the source tree.

What Is E3?

E3 is the third generation emulator for the Kestrel-3 home-brew computer. This emulator is intended to facilitate system software development as well as I/O core (hardware) development if required. As of right now, the emulator isn't intended to be a general purpose replacement for the computer; however, with some tender loving care and careful attention to detail when maintaining the software, I see no reason why it cannot evolve into something on par with, say, VICE (a Commodore 8-bit family emulator).

What Can You Do With E3 Right Now?

As I write this document, E3 is (deliberately) limited in scope, especially compared to what most people think of when they think about emulators. For example, a NES emulator is expected to let you play games, and a Commodore 64 emulator should fully support the kinds of software you run on that platform, like GEOS, games, or music composition software. E3 is a little bit different in scope, however; it is not intended to be a complete representation of the finished hardware. Indeed, the finished hardware doesn't exist yet! E3's role in Kestrel-3 development is primarily to help me (and others who wish to join in!) define and/or refine what the finished hardware is supposed to be.

The Kestrel-3 philosophy is explicitly to focus on a small, expandable core system design first. In order to facilitate development of the smallest FPGA configuration of the Kestrel-3 computer, it currently emulates only the following features:

• The KCP53000B processor core.
• Up to 1MB of "Processor Card" ROM
• Up to 1MB of "Kestrel" ROM
• Configurable amount of RAM (defaults to 1MB).
• User Terminal Serial Interface

Note that there does not exist any particular target performance at this level of abstraction. The processor currently runs as fast as the emulator will allow it, as does all emulated I/O facilities. Of course, real hardware will have real limitations; the hardware processor implementation is expected to perform at about 6 million instructions per second, for example. But, for the purposes of just scoping out the project requirements, or developing the system software implementation, there's no current need to emulate 6 MIPS performance in the emulator.

Since the user interface is via a serial interface to a dumb terminal, the emulated computer isn't going to be visually impressive. If you can imagine an Apple I, TRS-80, or RC2014 computer without a video card, but with a 64-bit processor instead of an 8-bit processor, that's essentially what you'll have at your command. A VGA-compatible display and keyboard/mouse interface are on my list of things to implement in the future.

You'll also notice that mass storage is not yet implemented. That means you cannot load or save programs or data files. This is a known issue and I'll be working on this deficiency in the days to come as well.

Obtaining and Building E3

The following instructions have been tested on a fresh cloud hosted virtual machine running Ubuntu 19.04. You may need to adjust these installation instructions for your particular host operating system. To the greatest extent possible, the code snippets below are designed to be cut and pasted for your convenience.

Prerequisites and Dependencies

No convenient distributions of E3 exists to my knowledge. You'll need to acquire E3 using the Fossil source code management tool. Thankfully, most Linux distributions have convenient packages for recent versions of Fossil. You'll want Fossil version 2.0 or later.

sudo apt install -y fossil

The current Kestrel-2DX and Kestrel-3 development software (it's the same for both platforms) depends heavily upon Python 2.7 as well as a C compiler and its supporting development tools.

sudo apt install -y python gcc binutils make m4

After building the emulator, you'll need a dumb terminal to talk to the virtual Kestrel. I'm a fan of using minicom:

sudo apt install -y minicom

Checking Out the Code

I like to have a certain directory structure laid out when working with Fossil repositories. This directory structure is perhaps a bit overkill for me; however, it follows established best practices for Fossil repositories. Here's the script that I follow:

mkdir -p ${HOME}/fossils
cd ${HOME}/fossils
fossil clone http://chiselapp.com/user/kc5tja/repository/kestrel-3 kestrel-3.fossil
mkdir -p ${HOME}/projects/kestrel-3/trunk
cd ${HOME}/projects/kestrel-3/trunk
fossil open ${HOME}/fossils/kestrel-3.fossil

This is a bit more tedious than using something like Git, perhaps; however, the result will be a clean checkout.

If you ever want to bring your checkout up to the latest commit, the following command will do all the heavy lifting for you:

fossil pull

Compiling

Once you have a clone of the repository, building the software should be quite easy.

make

The build is nearly instantaneous on my computer; but if you really wanted to impress someone, you could always invoke a parallel build:

make -j$(nproc)

OPTIONAL: Note that there is no "make install" target; to "install" the executables this creates, you can place this command somewhere in your .profile or your shell's equivalent:

export PATH=${PATH}:${HOME}/projects/kestrel-3/trunk/dev/bin

Now, you should be able to invoke the tools without having to prefix each command with dev/bin/ all the time. Personally, I've grown used to dev/bin/, so that's how I'll illustrate the examples from here on.

Running E3

To invoke E3, I like to have two shell windows available. In the first shell window, you can invoke the following command to run DX-Forth in the emulator:

dev/bin/e3 -k firmware/dxforth/bin/kesrom.bin -p firmware/dxforth/bin/cpurom.bin

This should produce an output similar to (but maybe not exactly the same as) the following:

E Emulator; Version 3.0
This emulator is intended to facilitate software development 
for the Kestrel-3 family of homebrew computers by defining the 
minimally viable target for systems software development.

Processor ROM image file: firmware/dxforth/bin/cpurom.bin
Kestrel ROM image file  : firmware/dxforth/bin/kesrom.bin
Unused ROM fill byte    : 0xAA (170)
Processor ROM size      : 1048576
Kestrel ROM size        : 1048576
Kestrel RAM size        : 1048576

Processor ROM read      : 262200
Kestrel ROM read        : 9712
User terminal PTY: /dev/pts/2

The important part to note is the User terminal PTY report. Assuming everything went OK, the emulator is running, and although you cannot see it yet, the DX-Forth banner and OK prompt has already been printed.

Next, we need to connect to the emulator using a dumb serial terminal. I use minicom for this purpose in the other shell window:

minicom -p /dev/pts/2

NOTE: The "port" device that Minicom should connect to must be the same as the User terminal PTY report generated when running E3.

The console will not display anything, for E3 is busy waiting for input at this point. If you press the ENTER key a few times, you should see OK appear each time. To show the DX-Forth banner, you'll need to reboot the Forth environment. You can do this with the following command:

BYE

Note that DX-Forth is currently case sensitive. BYe, bye, and other case permutations will not work; you'll get an undefined word error.

Congradulations! You're running a minimally configured Kestrel-3 computer running a minimally featured Forth interpreter for firmware!

Option Reference

The -k option tells the emulator where to find the Kestrel ROM image. This can be any size file. If the file is smaller than 1MB, however, all unused space in the Kestrel ROM image is set to the current unused space byte ($AA by default). If the file is larger than 1MB, any content beyond 1MB will be ignored.

The -p option tells the emulator where to find the Processor Card ROM image. The limitations and features of the Processor Card ROM image are similar to those of the Kestrel ROM image.

If, for some reason you ever wish to use a different value for unused ROM space filler byte, you can provide the -u option. Note that the parameter must be expressed as a decimal integer; hexadecimal notation is not supported (yet). Any value between 0 and 255 will work. The default is 176 ($AA), which is a strange-enough value to make stray pointer dereferences stand out when debugging programs.

The icoBoard Gamma board comes equipped with at most 1MB of RAM. However, some models only come with 512KB. Future versions may target other FPGA boards which have different amounts of RAM. The -r option lets you control how much RAM your E3 instance has "installed". If left unspecified, it defaults to 1MB.

Exiting E3

There are two ways to exit from E3.

The first is to terminate Minicom using c-A X. After approving Minicom's confirmation, Minicom will exit. However, you should also see that E3 has exited as well. (There will be an I/O error related to SIA1 when this happens; this is normal.)

The alternative way is to terminate the emulator under program control. As documented in the memory map, SIA #1 (which is what talks to the user's attached console) appears at address $0000000080000000. The baud rate generator is the 32-bit word at offset 4 from this base address, or $0000000080000004. To exit the E3 emulator, you can set the baud rate to 95 bits per second and turn on all loopback modes at once. In Forth:

HEX FFFFFFFF 80000004 W!

This will not terminate Minicom; however, it will terminate E3. (Minicom will probably complain about the I/O port disappearing, however.)